\name{db.Rquery-class}
\Rdversion{1.1}
\docType{class}
\alias{db.Rquery-class}
\alias{db.Rview-class}

\title{Class \code{"db.Rquery"} and its sub-class \code{db.Rview-class}}
\description{
  An object of this class represents a series of operations applied onto
  an existing \code{\linkS4class{db.data.frame}} object. These
  operations are actually a SQL query, which one can choose to
  materialize in the database using
  \code{\link{as.db.data.frame}}. \code{\link{lk}} can fetch a part
  of the result of executing the SQL query. Thus one does not need to
  create a table for every step of the operations, and the data
  transfered between R and the database is minimized.
}

\section{Objects from the Class}{
Objects can be created by almost all functions/methods that can be
applied onto \code{\linkS4class{db.data.frame}} except
\code{\link{content}}, \code{\link{lk}} and \code{\link{delete}}.

\code{db.Rview-class} is a sub-class of \code{db.Rquery-class}, and it behaves just like "view" in the databases except that it exists only in R. Usually there is no difference to use \code{db.Rview} or \code{db.Rquery}. \code{\link{as.db.Rview}} casts a \code{db.Rquery} object into a \code{db.Rview} object.

Usually it is
NOT recommended to directly manipulate the internal slots of these objects.
}

\section{Slots}{
  \describe{
    \item{\code{.content}:}{
      Object of class \code{"character"}. The SQL query that represents
  the operations. The function \code{\link{content}} can get this value.
    }

    \item{\code{.expr}:}{
      Object of class \code{"character"}. An array of expression
      strings for columns of the table that the SQL query can be
      materialized into. It is not to used by the
      normal users.
    }

    \item{\code{.source}:}{
      Object of class \code{"character"}. A string, the table/view name
      which this SQL query is originated. It is not to used by the
      normal users.
    }

    \item{\code{.parent}:}{
      Object of class \code{"character"}. A string. In the SQl query it
      is the part after "from". It is not to used by the
      normal users.
    }

    \item{\code{.conn.id}:}{
      Object of class \code{"numeric"}, an integer. The ID number of the
      database
      connection where \code{.source} resides. The functions
      \code{\link{conn.id}} and \code{\link{conn.id<-}} can get and set
      this value.
    }

    \item{\code{.col.name}:}{
      Object of class \code{"character"}. An array of strings. The names
      of columns of the table that the SQL query can be materialized
      into. The
      S4 method \code{\link{names,db.obj-method}} gets this value.
    }

    \item{\code{.key}:}{
      Object of class \code{"character"}. The name of the primary key
      column name in \code{.source}. Currently only one primary key
      column is
      supported. This value can be set during the creation of the object
      when using the function \code{\link{db.data.frame}}. The functions
      \code{\link{key}} and \code{\link{key<-}} can be used to get and
      set this value.
    }

    \item{\code{.col.data_type}:}{
      Object of class \code{"character"}.  The 1D array of column data
      types of the table that the SQL query can be materialized
      into. This is not supposed to be used by the normal user.
    }

    \item{\code{.col.udt_name}:}{
      Object of class \code{"character"}. The 1D array of column udt
      names of the table that the SQL query can be materialized
      into. This is
      not to used by normal users.
    }

    \item{\code{.where}:}{
      Object of class \code{"character"}. The condition string used in
      "where" inside the SQL query.
    }

    \item{\code{.is.factor}:}{
      Object of class \code{"logical"}. An array of logical values which
      indicate whether each column of the table that the SQL query can
      be materialized
      into is a factor. This
      is not to be used by the normal users.
    }

    \item{\code{.factor.suffix}:}{
      Object of class \code{"character"}. An array of strings for
      every column. When creating dummy columns
      for a factor column, we add a random string in the names of the
      dummy columns to avoid naming conflicts. So a factor column's
      \code{.factor.suffix} is a random string, otherwise it is just an
      empty string. This is not to be used by the normal users.
    }

    \item{\code{.factor.ref}:}{
      The value of the factor reference level for the regressions. If it       is \code{NA}, then the regressions automatically select a reference level.
    }

    \item{\code{.sort}:}{
      Object of class \code{"list"}. The list contains the information
      used for "order by" in the SQL query.

      by: A string. The column names that are used in "order by".

      order: A string, "" or "desc"

      str: A string, the full "order by ..." string.
    }

    \item{\code{.is.agg}:}{
      logical value, whether this object represents an aggregate
      operation.
    }

      \item{\code{.dist.by}:}{
    A string, the distribution policy for the original data table, which is used to construct this \code{db.Rquery} object, when using Greenplum database or HAWQ. It can be \code{character(0)}, which means the original data table is distributed randomly. Or it can be a string of column names separated by comma, which are the columns that are used in the "distributed by" when the original table was created.
  }
  }
}

\section{Extends}{
Class \code{"\linkS4class{db.obj}"}, directly.
}

\section{Methods}{
All methods for \code{\linkS4class{db.data.frame}} can be applied onto
this class.
}

\author{
  Author: Predictive Analytics Team at Pivotal Inc.

  Maintainer: Frank McQuillan, Pivotal Inc. \email{fmcquillan@pivotal.io}
}

\seealso{
  \code{\link{db.data.frame}} creates a \code{db.data.frame} object.

  \code{\link{as.db.data.frame}} converts \code{db.Rquery} object,
  \code{data.frame}, or a data file into a \code{db.data.frame} object
  and at the same time creates a new table in the database.

  \code{\link{as.db.Rview}} converts a \code{db.Rquery} object to a \code{db.Rview} object.

  \code{\linkS4class{db.obj}} is the superclass.

  Class \code{\linkS4class{db.data.frame}} is another sub-class of
  \code{\linkS4class{db.obj}}.

  \code{\link{lk}} display a part of the table
}

\examples{
\dontrun{
showClass("db.Rquery")

%% @test .port Database port number
%% @test .dbname Database name
## set up the database connection
## Assume that .port is port number and .dbname is the database name
cid <- db.connect(port = .port, dbname = .dbname)

delete("abalone", conn.id = cid)
x <- as.db.data.frame(abalone, "abalone", conn.id = cid)

## create several db.Rquery objects
y <- x[,1:2]
z <- x[x$rings > 10,]

dim(z) # get an error

lk(y)

lk(z)

## materialize a db.Rquery object
z <- as.db.data.frame(z, "abalone_rings_larger_10")
delete("abalone_rings_larger_10", conn.id = cid)

dim(z) # no error

db.disconnect(cid, verbose = FALSE)
}
}

\keyword{classes}
\keyword{database}
